{
    title:  'Configuring Expansive',
    crumbs: [ 
        { "User's Guide": "index.html" },
    ],
}

        <h1>Configuring Expansive</h1>
        <p>Expansive is configured by an <em>expansive.json</em> file that defines the top level configuration
        for the site and controls how Expansive renders the site. It specifies initial meta data, directory names, 
        file patterns to process, ports to serve and processing instructions. Expansive uses sensible defaults 
        so you typically do not need to configure much. An expansive.json file must be present for Expansive 
        to operate.</p>

        <p>Here is a typical expansive.json file:</p>

        <code class="inverted">{
    meta: {
        site: 'https://embedthis.com/',
    },
    control: {
        copy: [ 'images' ],
        listen: '127.0.0.1:4000'
    },
    "release": {
        "services": {
            "css": {
                "minify": true
            },
            "js": {
                "usemap": false
            }
        }
    }
}</code>

        <p>The <em>meta</em> property section defines the default public URL for the site and also provides
        data properties that may be used in content pages. The <em>copy</em> property provides a 
        hint to Expansive that anything under the 'images' directory should be copied and not processed 
        by the Expansive pipeline. The <em>services</em> property set provides configuration for the 
        plugin services to control their operation and enable/disable minification.</p> 

        <h2>Creating expansive.json</h2>
        <p>To create an expansive.json file, use <em>expansive init</em>.</p>
        <code class="inverted">$ expansive init</code>

        <p>Alternatively, install a ready-made Expansive skeleton package that includes an 
        <em>expansive.json</em> file such as 
        <a href="https://github.com/embedthis/exp-html-skeleton">exp-html-skeleton</a>.</p>
        <code class="inverted">$ pak install exp-html-skeleton</code>

        <h2>Control Properties</h2>
        <p>These are the standard properties in the <em>control</em> collection in <em>expansive.json</em>.</p>

        <table class="ui celled table" title="control">
            <thead>
                <tr><th>Name</th><th>Description</th></tr>
            </thead>
            <tbody>
                <tr><td>copy</td><td>Array of patterns to copy without processing. The patterns may include 
                    <em>*</em> or <em>**</em>. If a directory is specified, all files under the directories copied. 
                    The files are relative to the <em>contents</em> directory.</td></tr>
                <tr><td>documents</td><td>Array of patterns to process. The patterns may include 
                    <em>*</em> or <em>**</em>. If a directory is specified, all files under the directories 
                    are copied. The files are relative to the top-level directory.</td></tr>
                <tr><td>files</td><td>Array of directories containing raw content to copy to <em>dist</em> 
                    without processing. By default, contains <em>files</em>.</td></tr>
                <tr><td>listen</td><td>Address on which to listen for HTTP requests. May be just a port number.</td></tr>
                <tr><td>script</td><td>Script to evaluate to inject code into the Javascript global execution
                    context. This is visible to scripting in all pages.</td></tr>
                <tr><td>pipeline</td><td>Hash of extension mappings to a list of transform services for those 
                    mappings. Mappings are in the form <em>ext -&gt; ext</em>. For example:
                    <code>transforms: {
    'less -&gt; css': [ 'less', 'css-prefix', 'css-minify', 'gzip' ]
    'pre': [ 'blog', 'analytics', gzip' ]
}</code>
                    <p>The special names <em>pre</em> and <em>post</em> may be used to specify the transform order
                    for invoking pre and post processor transform callbacks.</p>

                    <p>Some of the standard transform names are: <em>esp</em>, <em>less</em>, 
                    <em>markdown</em>, <em>sass</em>, <em>gzip</em>, <em>css-minify</em>, 
                    <em>js-minify</em>, <em>css-prefix</em>, and <em>shell</em>.</p></td></tr>
                <tr><td>watch</td><td>Time in milliseconds to wait between checking for rendering.</td></tr>
            </tbody>
        </table>
        
        <h2>Sample expansive.json</h2>
        <p>Here is a sample expansive.json configuration file for an 
            <a href="http://angularjs.org/">Angular application.</a></p>
        <code class="inverted">{
    meta: {
        site: 'https://embedthis.com/appweb/demo/',
        sitemap: {
            files: [
                '**.html',
                '!missing.html',
                '!unsupported.html'
            ]
        }
    },
    services: {
        'clean-css': true
    },
    debug: {
        services: {
            compress: false,
            'js': {
                usemap: false,
            },
            'angular': {
                'html': false,
                'package': false
            }
        }
    },
    release: {
        services: {
            compress: false,
            'css': {
                minify: true
            },
            'js': {
                usemap: false
            },
            'angular': {
                'html': true,
                'js': true,
                'package': true,
                'scripts': [
                    'contents/**.js',
                    'lib/esp*/**.js',
                    'lib/angular*/**.js'
                ]
            }
        }
    }
}
</code>
